COMMENT ⊗   VALID 00003 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002				LATEX - Lisp-Augmented TEX
C00007 00003			       A Reference Manual for LATEX
C00019 ENDMK
C⊗;
			LATEX - Lisp-Augmented TEX

LATEX is a program which allows you to include LISP statements in a file which
contains input to TEX.  This gives TEX much more "programmability" than is pro-
vided by the language of macros.  LATEX translates its input into a standard TEX
input file, which is then run as usual.

A LATEX input file (usually given the extension .LTX) contains TEX input, along
with LISP statements inserted between "break" characters.  The break character
is initially "@", but you can change it at any time.  When a break character is
encountered, everthing up to the next break character is interpreted by MACLISP.
After the closing break character, LATEX resumes copying to its output file.

An example:  Suppose you wanted a list of the first 200 primes.
	On the file PRIMES.LTX, write

		\input basic
		@(setq numprimes 200)@
		The first @numprimes@ primes are: $$ 2
		@(defun prime (p)
			(do ((d 3 (+ d 2))(lim (sqrt p)))
			    ((greaterp d lim) t)
			    (cond ((zerop (remainder p d)) (return nil)))))

		(defun nextprime (n)
		       ((lambda (m)
				(cond ((prime m) m)
				      (t (nextprime m))))
			(+ n 2)))

		(do ((i 1 (1+ i)) (p 1) (k 0 (1+ k)))
		    ((= i numprimes))
		    (output ",")
		    (cond ((= k 10) (setq k 0) (output "
		")))
		    (output (setq p (nextprime p))))
		
		@.$$
		\vfill
		\eject

	(This is on PRIMES.LTX[TEX,JJW] if you want to actually try it.)
	Now type "R LATEX" and follow its instructions.  On the file
	PRIMES.TEX you will get:

		\input basic

		The first 200 primes are: $$ 2
		,3,5,7,11,13,17,19,23,29,31,
		37,41,43,47,53,59,61,67,71,73,
		79,83,89,97,101,103,107,109,113,127,
		131,137,139,149,151,157,163,167,173,179,
		181,191,193,197,199,211,223,227,229,233,
		239,241,251,257,263,269,271,277,281,283,
		293,307,311,313,317,331,337,347,349,353,
		359,367,373,379,383,389,397,401,409,419,
		421,431,433,439,443,449,457,461,463,467,
		479,487,491,499,503,509,521,523,541,547,
		557,563,569,571,577,587,593,599,601,607,
		613,617,619,631,641,643,647,653,659,661,
		673,677,683,691,701,709,719,727,733,739,
		743,751,757,761,769,773,787,797,809,811,
		821,823,827,829,839,853,857,859,863,877,
		881,883,887,907,911,919,929,937,941,947,
		953,967,971,977,983,991,997,1009,1013,1019,
		1021,1031,1033,1039,1049,1051,1061,1063,1069,1087,
		1091,1093,1097,1103,1109,1117,1123,1129,1151,1153,
		1163,1171,1181,1187,1193,1201,1213,1217,1223.$$
		\vfill
		\eject

	which TEX will happily accept.

Admittedly, this is a trivial example, but you can see the general idea.  The
next few pages of this file discuss LATEX in more detail.

[If you tried the example, you will notice that it runs pretty slowly.  Most of
the time is due to MACLISP interpreting the functions, not due to LATEX.]
		       A Reference Manual for LATEX

The basic idea of LATEX is very simple: LISP functions are defined and executed
in the middle of a TEX input file, and they can insert strings into this file.
There are virtually no restrictions on what you are allowed to ask MACLISP to do
for you.


BREAK CHARACTER
---------------

The break character is initially set to "@".  To change it, say to "&", you say
@(brchar "&")&. Two points are worth mentioning:

     1. The new break character takes effect immediately (as soon as we reach
	the right parenthesis), and so it is used to get out of LISP mode and
	back into TEX mode.  If we wanted to do more than just change the break
	character, then   @(brchar "&") (...other stuff...)& would work.
     2. The break character is typed between double quotes.  This is the usual
	form for a string in LISP.

What BRCHAR does is convert its argument from a string to a number which is is
the ascii code of (the first character of) that string.  This number is assigned
to the variable BRCHAR.  Thus saying @(setq brchar 38)& would do the same thing
as above, except it requires you to know the ascii code.

If you want to include the current break character in the TEX file, there are
two cases:

     1.	You can place  ... @@ ...  in the input file, and LATEX will convert this
	to  ... @ ... in the output file, but
     2. If you are executing a LISP form, then the break character should not be
	typed twice; this is because the LISP reader takes over as soon as LATEX
	sees an open parenthesis between break characters.  Therefore, the form
		... @(repeat 20 (output "@"))@ ...
	will put 20 at-signs into the output file.  (See below for the use of
	REPEAT.)

The closing break character will not catch unmatched parentheses; instead, the
LISP reader will read right over it, but will almost certainly detect an error
quite shortly thereafter.


NUMBERS
-------

All numbers are input and output in decimal, not octal.  If you change the base
back to octal, some of the conversion routines used by OUTPUT may not work.


ATOMIC FORMS
------------

An atomic form in LISP is an expression which is not the result of a function
call.  The second line of the example above is

		The first @numprimes@ primes are: $$ 2

and in this line, "numprimes" is an atomic form.  It makes no sense for LATEX
just to evaluate this, since that would produce no change in the output file,
and therefore have no effect at all.  LATEX treats this as if it were

		The first @(output numprimes)@ primes are: $$ 2

and thus causes the current value of NUMPRIMES to be placed in the output file.
(See the discussion of OUTPUT below.)  This rule is applied to all atomic forms
in the input file which are at "top-level", i.e. which MACLISP would evaluate
on-the-spot and print for you.


THE FUNCTION "OUTPUT"
---------------------

This function has been predefined, and causes LATEX to write information into
the output file.  One of the most common uses of OUTPUT is with a string
argument, i.e.

	(output "Any string of characters").

Note that carriage returns, line feeds, etc. are all legal between the double
quotes.  If OUTPUT is given a numeric argument, it is treated somewhat special-
ly:  a fixnum is output in decimal, and the trailing period supplied by MACLISP
is supressed; a flonum is output in fixed-point notation, e.g. where MACLISP
gives 7.5E-4, OUTPUT will output the number as 0.00075 so that constructs like

	\vskip@(output (times x y))@pt

don't cause a TEX error for small values of  X*Y.

OUTPUT can take an arbitrary number of arguments.  For example,

	@(output 2 " plus " 2 " is " (+ 2 2))@

sends the characters  "2 plus 2 is 4"  to the output file.

The global variable CRLF has been preset to the two-character string
<carriage-return><line-feed>.  Use this as an argument to OUTPUT when a
series of OUTPUTs would create a line too long for TEX, or to make the TEX
file more readable.


MULTIPLE OUTPUT FILES
---------------------

LATEX can write to several output files at once.  To declare an auxiliary
output file, include the LISP form

	(outfile filex "foo.bar")

which declares FILEX to be a file named FOO.BAR and opens it, and then say

	(outputf filex item1 ... itemn)

to send output to the file.  Note that this clobbers any existing file named
FOO.BAR.  The first argument to OUTFILE is not evaluated, but the second is.
Thus you may say

	@(princ "Give me a filename: ")
	 (outfile ff (readline))@

to get a filename from the terminal at the time LATEX is processing its input.
The variable OUTF contains the default output file; i.e.

	(output abc)  is equivalent to	(outputf outf abc).


OTHER USEFUL FUNCTIONS
----------------------

LATEX has several useful predefined functions.	OUTPUT has already been men-
tioned.  Another one is REPEAT, which causes a LISP form to be evaluated several
times in succession.  Saying

	(repeat n foo)

is like saying foo  n  times.  The rule for atomic forms doesn't apply here, so
to get the value of the variable  X  into the TEX file 10 times you must say

	@(repeat 10 (output x))@

To control what happens when LATEX exits, there are two functions ENDRUN and
ENDTEXT.  ENDRUN takes the name of a processor, for example,

	@(endrun "maxtex")@

and causes a line of the form

	rer name↔\input fname↔

to be put in the line editor when LATEX exits, where "name" is the name of the
processor, and "fname" is the name (without the extension ".TEX") of the file
on which LATEX wrote its output.  If you say  @(endrun nil)@, nothing will be
loaded into the line editor.  To place an arbitrary string in the line editor,
use the function

	@(ENDTEXT string)@


ERRORS
------

For the most part, you are on your own with respect to MACLISP errors.	When
something happens wrong in your LISP functions, MACLISP will act just as it
always does, which usually means going into a break loop.  The only errors which
LATEX is currently set up to catch are those which occur while it is reading in
filenames.  In this case, you see the MACLISP error message, but are given
another chance to type in the name.

LATEX can swap directly into the E editor at a point near where it thinks your
error is.  To do this, simply say   (E)   when MACLISP gives you an error message.
For this feature to work, you must follow one rule:

	Never begin a new page in E in the middle of a LISP expression.

LATEX will try to handle the case in which a page starts at "top-level" between
break characters [not yet implemented], but nothing is guaranteed.  For safety,
always follow the above rule.  If you don't, you will still swap to E, but
probably on the wrong page of your input file.

After making changes, you must start LATEX back at the beginning.  It is not
possible to start up again where you left LATEX, because swapping to E closes
your files.

If you want to quit without entering E, the function  (STOP)  is better than
(QUIT)  or using the CALL key, since it will close your files first.